Command:
useLog
Synopsis:
useLog $strPathName 
OR
useLog $nLogObjectId
Arguments:

$strPathName - Pathname of a file to which to direct all log output. This path may be relative or absolute. The file doesn't have to exist. If it does, its existing content will be overwritten.

$nLogObjectId - The log object identifier of an existing log object. Note that you can obtain the log object identifier of the current log object by using the getCurrentLogfileId command.

Returns:
If successful, the function returns an empty string. Otherwise it returns a string containing a very brief error message.
Availability:
Since version 01.01.00.

Use this command to switch to another logfile while a script is being run. The first form of invocation switches to a new logger whereas the second form of invocation switches to an already existing logger.


Example:
# Get the id of the current log.
set nInitialLogId [ getCurrentLogfileId ]

DPrint "This sentence is printed to our initial log object, but we're going to switch in a second."

# Switch to a new logfile.
useLog "MyNewLogfile.log"

DPrint "Unlike the first sentence, this one is __NOT__ printed to our initial log but goes to the new log we just opened."

# Switch back to our initial log file.
set strReturnValue [ useLog $nInitialLogId ]

if { strReturnValue == "" } {
    # Yay! It worked!
    DPrint "Successfully switched back to our initial log."
} else {
    # Shucks! Something went wrong.
    DPrint "Failed to switch back to our initial log. Maybe we specified the wrong id or something ...?"
}